---
title: gluestack-ui Toast Component | Installation, Usage, and API

description: A toast is a modal overlay that displays alerts or notifications, crucial for user updates.

pageTitle: Toast

pageDescription: A toast is a modal overlay that displays alerts or notifications, crucial for user updates.

showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="with-nativewind/Components/Feedback/Toast" />

import {
  Toast,
  ToastTitle,
  ToastDescription,
  useToast,
  ButtonGroup,
  Button,
  ButtonText,
  CheckCircleIcon,
  HelpCircleIcon,
  Icon,
  CloseIcon,
  VStack,
  HStack,
  Pressable,
  Avatar,
  AvatarImage,
  AvatarFallbackText,
  Text,
  Heading,
  Box,
  Divider,
  Center
} from '../../core-components/nativewind';
import { transformedCode } from '../../utils';
import {
  AppProvider,
  CodePreview,
  Table,
  TableContainer,
  InlineCode,
  CollapsibleCode,
  Tabs,
} from '@gluestack/design-system';
import { View } from 'react-native';
import Wrapper from '../../core-components/nativewind/Wrapper';
import { RefreshCw, Send, AlertTriangle } from 'lucide-react-native';
import AnatomyImage from '../../extra-components/nativewind/AnatomyImage';

This is an illustration of **Toast** component.

<Wrapper>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={true}
    metaData={{
      code: `
        function Example() {
          const toast = useToast();
          const [toastId, setToastId] = React.useState(0);
          const handleToast = () => {
            if (!toast.isActive(toastId)) {
              showNewToast();
            }
          };
          const showNewToast = () => {
            const newId = Math.random();
            setToastId(newId);
            toast.show({
              id: newId,
              placement: 'top',
              duration: 3000,
              render: ({ id }) => {
                const uniqueToastId = "toast-" + id;
                return (
                  <Toast nativeID={uniqueToastId} {...props}>
                    <ToastTitle>Hello!</ToastTitle>
                    <ToastDescription>
                      This is a customized toast message.
                    </ToastDescription>
                  </Toast>
                );
              },
            });
          };
          return (
            <Button onPress={handleToast}>
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        }
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Button,
        ButtonText,
      },
      argsType: {
        action: {
          control: 'select',
          options: ['success', 'info', 'error', 'warning', 'muted'],
          default: 'muted',
        },
        variant: {
          control: 'select',
          options: ['solid', 'outline'],
          default: 'solid',
        },
      },
    }}
  />
</Wrapper>

<br />

## Installation

<Tabs value="cli" type="section">
  <Tabs.TabList>
      <Tabs.Tab value="cli">
        <Tabs.TabTitle>CLI</Tabs.TabTitle>
      </Tabs.Tab>
     <Tabs.Tab value="manual">
        <Tabs.TabTitle>Manual</Tabs.TabTitle>
     </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="cli">
<>

### Run the following command:
  ```bash
  npx gluestack-ui add toast
  ```
</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="manual"> 
<>

### Step 1: Install the following dependencies:

```bash

npm i @gluestack-ui/toast

```

### Step 2: Copy and paste the following code into your project.

<CollapsibleCode>

```jsx 
%%-- File: core-components/nativewind/toast/index.tsx --%% 
```

</CollapsibleCode>

### Step 3: Update the import paths to match your project setup.
</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

## API Reference

To use this component in your project, include the following import statement in your file.

```jsx
import { useToast, Toast } from '@/components/ui/toast';
```

<AnatomyImage mobileUrl='https://i.imgur.com/hESv96t.png' webUrl='https://i.imgur.com/onUcTTR.png' classNameStyle='aspect-[513/399] md:aspect-[736/283]' />

```jsx
export default () => (
  <Toast>
    <ToastTitle />
    <ToastDescription />
  </Toast>
);
```
### Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

#### Toast

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>duration</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>number or null</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>5000</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`The delay before the toast hides (in milliseconds). If set to null, toast will never dismiss.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>onCloseComplete</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`()=>{}`}</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Callback function to run side effects after the toast has closed.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>placement</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              'top'| 'top right' | 'top left' | 'bottom' | 'bottom left' |
              'bottom right'
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bottom</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>Position of toast on the web page.</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>render?: (props: any)</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>ReactNode</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>Renders a toast component</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>avoidKeyboard</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`If true and the keyboard is opened, the Toast will move up equivalent to the keyboard height.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>containerStyle</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>ViewStyle</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>Container style object for the toast.</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>

#### ToastTitle

Contains all Text related layout style props and actions.
It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

#### ToastDescription

Contains all Text related layout style props and actions.
It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

### Accessibility

We have outlined the various features that ensure the Toast component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the [WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/).

#### Keyboard

- `Tab + Enter`: Triggers the toast's action.

#### Screen Reader

- VoiceOver: When the toast is focused, the screen reader will announce the toast's title.

### Props

Toast component is created using View component from react-native. It extends all the props supported by [React Native View](https://reactnative.dev/docs/view#props) and the props mentioned below.

#### Toast

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Name</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Value</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>action</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              error | warning | success | info | attention
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>attention</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>variant</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>solid | outline | accent</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>solid</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>

### Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

#### Toast in note talking platform

<Wrapper>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        function Example() {
          const toast = useToast();
          const [toastId, setToastId] = React.useState(0);
          const handleToast = () => {
            if (!toast.isActive(toastId)) {
              showNewToast();
            }
          };
          const showNewToast = () => {
            const newId = Math.random();
            setToastId(newId);
            toast.show({
              id: newId,
              placement: 'top',
              duration: 3000,
              render: ({ id }) => {
                const uniqueToastId = "toast-" + id;
                return (
                  <Toast
                    action="error"
                    variant="outline"
                    nativeID={uniqueToastId}
                    className="p-4 gap-6 border-error-500 w-full shadow-hard-5 max-w-[443px] flex-row justify-between"
                  >
                    <HStack space="md">
                      <Icon
                        as={HelpCircleIcon}
                        className="stroke-error-500 mt-0.5"
                      />
                      <VStack space="xs">
                        <ToastTitle className="font-semibold text-error-500">Error!</ToastTitle>
                        <ToastDescription size="sm">
                          Something went wrong.
                        </ToastDescription>
                      </VStack>
                    </HStack>
                    <HStack className="min-[450px]:gap-3 gap-1">
                      <Button variant="link" size="sm" className="px-3.5 self-center">
                        <ButtonText>Retry</ButtonText>
                      </Button>
                      <Pressable onPress={() => toast.close(id)}>
                        <Icon as={CloseIcon} />
                      </Pressable>
                    </HStack>
                  </Toast>
                );
              },
            });
          };
          return (
            <Button onPress={handleToast}>
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        }
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Button,
        ButtonText,
        Pressable,
        Icon,
        CloseIcon,
        HelpCircleIcon,
        HStack,
        VStack
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Social media notification 

<Wrapper>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
      function Example() {
          const toast = useToast();
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement:"top",
                  render: ({ id }) => {
                    const toastId = "toast-" + id;
                    return (
                      <Toast
                        nativeID={toastId}
                        className="p-4 gap-3 w-full sm:min-w-[386px] bg-background-0 shadow-hard-2 flex-row"
                      >
                        <Avatar>
                          <AvatarFallbackText>JS</AvatarFallbackText>
                          <AvatarImage
                            source={{
                              uri: 'https://s3-alpha-sig.figma.com/img/cc35/9a95/ecf9cba1881effe726061fc6f4809371?Expires=1721001600&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=Pyj83N4SzedRQj~mtWMGxuhBcBMcuGc6ppsgWMnKDu2iEEcD-NQaE2WHgwqq6k7uHxzBd~gecQN2HXDrkVTlxvryARvD8Ai5RkaicN8OdqqHojHdmT8y1Q1IPKjSf0HxHA0EgkkTS8RLqRXBwrXV6IaGsVKNxche92mdvCt0llYhzeQO0xLYOYIDUiOXONpcpP72QgRMZLbU3Ep2thUnwl6VuxFiphQPOKkLLUEeGhQF5KDQB71NG09Ypq2V3okej6dtPb0eo~IunDKiFIfDUwrj~2fD6Y~JRrVhmSIXloZlAPwCd37NwzT-Jl8pR4JIWqF4dRigx67HOSUExrezJg__',
                            }}
                          />
                        </Avatar>
                        <VStack className="w-full">
                          <HStack className="justify-between w-full">
                            <Heading
                              size="sm"
                              className="text-typography-950 font-semibold"
                            >
                              Jacob Steve
                            </Heading>
                            <Text size="sm" className="text-typography-500">
                              2m ago
                            </Text>
                          </HStack>
                          <Text size="sm" className="text-typography-500">
                            commented on your photo
                          </Text>
                        </VStack>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Show Toast</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Button,
        ButtonText,
        Pressable,
        Icon,
        CloseIcon,
        CheckCircleIcon,
        HStack,
        VStack,
        Avatar,
        AvatarFallbackText,
        AvatarImage,
        Heading,
        Text
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Software update toast

<Wrapper>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
      function Example() {
        const toast = useToast();
        const [toastId, setToastId] = React.useState(0);
        const handleToast = () => {
          if (!toast.isActive(toastId)) {
            showNewToast();
          }
        };
        const showNewToast = () => {
          const newId = Math.random();
          setToastId(newId);
          toast.show({
            id: newId,
            placement: 'top',
            duration: 3000,
            render: ({ id }) => {
              const uniqueToastId = "toast-" + id;
              return (
                <Toast
                  nativeID={uniqueToastId}
                  className="p-4 gap-4 w-full max-w-[386px] bg-background-0 shadow-hard-2 flex-row"
                >
                  <Box className="h-11 w-11 items-center justify-center hidden min-[400px]:flex bg-background-50">
                    {\/* RefreshCw is imported from 'lucide-react-native' *\/}
                    <Icon
                      as={RefreshCw}
                      size="xl"
                      className="stroke-background-800"
                    />
                  </Box>
                  <VStack space="xl">
                    <VStack space="xs">
                      <HStack className="justify-between">
                        <ToastTitle className="text-typography-900 font-semibold">
                          Update available
                        </ToastTitle>
                        <Pressable onPress={() => toast.close(id)}>
                          <Icon as={CloseIcon} className="stroke-background-500" />
                        </Pressable>
                      </HStack>
                      <ToastDescription className="text-typography-700">
                        A new software version is available for download.
                      </ToastDescription>
                    </VStack>
                    <ButtonGroup className="gap-3 flex-row">
                      <Button
                        action="secondary"
                        variant="outline"
                        size="sm"
                        className="flex-grow"
                      >
                        <ButtonText>Not now</ButtonText>
                      </Button>
                      <Button size="sm" className="flex-grow">
                        <ButtonText>Update</ButtonText>
                      </Button>
                    </ButtonGroup>
                  </VStack>
                </Toast>
              );
            },
          });
        };
        return (
          <Button onPress={handleToast}>
            <ButtonText>Press Me</ButtonText>
          </Button>
        );
      }
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Button,
        ButtonText,
        Pressable,
        Icon,
        CloseIcon,
        HStack,
        VStack,
        Box,
        RefreshCw,
        ButtonGroup
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Message sent toast

<Wrapper>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
      function Example() {
          const toast = useToast();
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement:"top",
                  render: ({ id }) => {
                    const toastId = "toast-" + id;
                    return (
                      <Toast
                        nativeID={toastId}
                        className="px-5 py-3 gap-4 shadow-soft-1 items-center flex-row"
                      >
                        {\/* Send is imported from 'lucide-react-native' *\/}
                        <Icon
                          as={Send}
                          size="xl"
                          className="fill-typography-100 stroke-none"
                        />
                        <Divider
                          orientation="vertical"
                          className="h-[30px] bg-outline-200"
                        />
                        <ToastTitle size="sm">Message sent successfully</ToastTitle>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Show Toast</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        Wrapper,
        Toast,
        ToastTitle,
        useToast,
        Button,
        ButtonText,
        Icon,
        Send,
        Divider
      },
      argsType: {},
    }}
  />
</Wrapper>
